Skip to main content

​
Introduction

The Agents Module provides comprehensive functionality for managing AI agents, creating tasks, and executing workflows within the xpander.ai platform.

​
Overview

In this module, you can:
  • List, retrieve, and manage multiple AI agents
  • Load specific agents and interact with their components
  • Export agents as templates and import them across organizations
  • Manage tasks, tools, and knowledge bases associated with each agent
  • Retrieve, manage, and delete user sessions for agents with session storage
  • Access configurable elements like MCP (Model Context Protocol) servers

​
Examples

​
Listing all Agents

This example demonstrates how to list all available agents in both asynchronous and synchronous styles.

​
Asynchronous Example

Using alist() to retrieve agents asynchronously: 
from xpander_sdk import Agents, AgentDeploymentType

agents = Agents()
agents_list = await agents.alist()
for agent in agents_list:
    print(f"Agent: {agent.name} (ID: {agent.id})")
    # Load full agent details to access deployment_type
    full_agent = await agent.aload()
    print(f"Deployment Type: {full_agent.deployment_type}")

​
Synchronous Example

Using list() to retrieve agents synchronously: 
from xpander_sdk import Agents

agents = Agents()
agents_list = agents.list()
for agent in agents_list:
    print(f"Agent: {agent.name} (ID: {agent.id})")

​
Loading a Specific Agent

Learn how to load a specific agent by its ID, which allows you to interact with its tools and tasks.

​
Asynchronous Example

agent = await agents.aget("agent-123")
print(f"Agent name: {agent.name}")

​
Synchronous Example

agent = agents.get("agent-123")
print(f"Agent name: {agent.name}")

​
Creating and Managing Tasks

This section illustrates creating, managing, and executing tasks assigned to agents.

​
Asynchronous Example

task = await agent.acreate_task(
    prompt="Analyze this dataset",
    file_urls=["https://example.com/data.csv"],
    events_streaming=True,
    output_format=OutputFormat.Json
)

​
Synchronous Example

task = agent.create_task(
    prompt="Analyze this dataset",
    file_urls=["https://example.com/data.csv"],
    events_streaming=True,
    output_format=OutputFormat.Json
)
For more details on task management, see the [Tasks API Reference](/API reference/tasks/API reference).

​
Session Management

Manage user sessions for agents using the Agno framework with session storage.

​
Asynchronous Example

from xpander_sdk import Agent

# Load agent
agent = await Agent.aload("agent-123")

# Get all sessions for a user
sessions = await agent.aget_user_sessions(user_id="user_123")
print(f"User has {len(sessions)} sessions")

# Retrieve specific session
session = await agent.aget_session(session_id="sess_456")
if session:
    print(f"Session ID: {session.session_id}")
    print(f"Messages: {len(session.messages)}")

# Delete a session
await agent.adelete_session(session_id="sess_456")
print("Session deleted")

​
Synchronous Example

agent = Agent.load("agent-123")

# Get all user sessions
sessions = agent.get_user_sessions(user_id="user_123")

# Get specific session
session = agent.get_session(session_id="sess_789")

# Delete session
agent.delete_session(session_id="sess_789")
Note: Session management is only supported for agents using the Agno framework with session storage enabled.

​
Agent Import & Export

Agent templates and cross-organization sharing are currently available via the REST API: 
import requests

# Export an agent
response = requests.post(
    f"https://api.xpander.ai/v1/agents/{agent_id}/export",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "name": "My Agent Template",
        "description": "Template for customer support",
        "icon": "🎧",
        "with_knowledge_bases": True
    }
)
template = response.json()
print(f"Template ID: {template['id']}")

# Import a template
response = requests.post(
    f"https://api.xpander.ai/v1/agents/template_import/{template_id}",
    headers={"x-api-key": "YOUR_API_KEY"},
    json={
        "name": "My Imported Agent",
        "with_knowledge_bases": True
    }
)
agent = response.json()
print(f"Imported Agent ID: {agent['id']}")
For comprehensive documentation on agent templates and cross-account sharing, see:
  • [Export Agent](/API reference/v1/agents/export-agent) - REST API endpoint
  • [Import Agent](/API reference/v1/agents/import-agent) - REST API endpoint
  • Agent Import & Export Guide - Complete guide
Continue to the [Agents API Reference](/API reference/agents/API reference) for detailed documentation on classes and methods.